Skip to content

feat: Python Self-Healing Supply Chain Demo (Interactive + Gemini 3)#13

Open
heiko-hotz wants to merge 25 commits intoUniversal-Commerce-Protocol:mainfrom
heiko-hotz:feature/self-healing-supply-chain-python
Open

feat: Python Self-Healing Supply Chain Demo (Interactive + Gemini 3)#13
heiko-hotz wants to merge 25 commits intoUniversal-Commerce-Protocol:mainfrom
heiko-hotz:feature/self-healing-supply-chain-python

Conversation

@heiko-hotz
Copy link

@heiko-hotz heiko-hotz commented Jan 13, 2026

feat: Python Self-Healing Supply Chain Demo (Interactive + Gemini 3)

📝 Summary

This PR adds a comprehensive Python sample demonstrating an Autonomous Supply Chain Agent capable of "Self-Healing" when a primary supplier fails. It leverages the Google Agent Development Kit (ADK) and the latest Gemini 3 Flash model to orchestrate a recovery workflow using UCP (Commerce) and AP2 (Governance) protocols.

✨ Key Features

  • Interactive Simulation: Includes a CLI-based InventoryManager where users simulate sales. The Autonomous Restock triggers automatically when inventory drops below a critical threshold.
  • Dynamic Discovery (UCP): The agent dynamically resolves backup suppliers via /.well-known/ucp instead of hardcoded endpoints, demonstrating true network autonomy.
  • Negotiation Capability (UCP): Handles multi-step checkout flows, including providing Shipping Address and Discount Codes (PARTNER_20) to finalize Tax and Totals.
  • Governance & Trust (AP2):
    • Implements Detached JWS signatures for verifiable user intent.
    • Enforces a Variance-Based Spending Policy (15% threshold).
    • Human-in-the-Loop: High-variance transactions pause for manual admin sign-off.
  • Modern Stack: Built with google-genai (Gemini 3 Flash Preview) and standard pydantic models for UCP/AP2 schemas.

🏗️ Architecture

  • buyer_agent.py: The ADK Agent utilizing a "Brain + Tools" pattern.
  • supplier_server.py: A lightweight Mock UCP Server (FastAPI) that handles Discovery, Checkout Negotiation, and Mandate Verification.
  • mock_db.py: Simulates a Product Catalog and Corporate Spending Policy.

🧪 How to Test

  1. Start the Supplier Server:
    python supplier_server.py
  2. Run the Buyer Agent:
    python buyer_agent.py
  3. Interactive Loop:
    • Enter sales (e.g., 90 units) to drop inventory below 20.
    • Observe the Agent detect the Primary Supplier failure (503).
    • Watch the Agent discover the Backup Supplier and request approval for the price variance.
    • Approve the purchase to see the Inventory restock.

✅ Checklist

  • Code adheres to UCP & AP2 Architectural Best Practices.
  • Includes detailed README.md with production architecture diagrams.
  • Secrets managed via .env.local (excluded from git).
  • Dependencies listed in requirements.txt.

@heiko-hotz heiko-hotz requested a review from a team January 13, 2026 11:11
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

remove before merging


### 2. Install Dependencies
```bash
pip install fastapi uvicorn requests python-dotenv
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

add instructions to create a venv before installing dependencies

### 2. Install Dependencies
```bash
pip install fastapi uvicorn requests python-dotenv
# Note: google-adk, ucp-sdk, ap2-sdk are currently mocked or included in this demo structure.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can you explain this? I actually need to install these dependencies to be able to run the demo


### 2. Install Dependencies
```bash
pip install fastapi uvicorn requests python-dotenv
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

add a2a-sdk

### 2. Install Dependencies
```bash
pip install fastapi uvicorn requests python-dotenv
# Note: google-adk, ucp-sdk, ap2-sdk are currently mocked or included in this demo structure.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also, please add versions in the dependencies. consider adding requirements.txt instead

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

actually, saw there's a requirements.txt. just update this instruction then.

README.md Outdated
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

undo this

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

please put all the sample content under a2a/ - also move the existing sample under cymbal-retail-agent

* Google GenAI API Key

### 1. Environment Configuration
Create a `.env.local` file in the root directory:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

clarify this is not the actual root, but the base directory for this sample

@damaz91 damaz91 self-assigned this Feb 5, 2026
@heiko-hotz
Copy link
Author

Thanks for the feedback @damaz91 - all the suggestion have been incorporated

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants